home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 August: Tool Chest / Dev.CD Aug 00 TC Disk 2.toast / pc / sample code / human interface toolbox / scrollingeditfield / stupcontrol.h < prev   
Encoding:
C/C++ Source or Header  |  2000-06-23  |  7.3 KB  |  186 lines
  1. /*
  2.     File: STUPControl.h
  3.     
  4.     Description:
  5.         Scrolling Text User Pane (STUP) control support routines.
  6.     
  7.     Routines defined in this header file are implemented in the
  8.     file STUPControl.c
  9.     
  10.     These routines allow you to create (or use an existing) user
  11.     pane control as a scrolling edit text field.
  12.     
  13.     These routines use the refcon field inside of the user pane
  14.     record for storage of interal variables.  You should not
  15.     use the reference value field in the user pane control if you
  16.     are calling these routines.
  17.  
  18.     Copyright:
  19.         © Copyright 2000 Apple Computer, Inc. All rights reserved.
  20.     
  21.     Disclaimer:
  22.         IMPORTANT:  This Apple software is supplied to you by Apple Computer, Inc.
  23.         ("Apple") in consideration of your agreement to the following terms, and your
  24.         use, installation, modification or redistribution of this Apple software
  25.         constitutes acceptance of these terms.  If you do not agree with these terms,
  26.         please do not use, install, modify or redistribute this Apple software.
  27.  
  28.         In consideration of your agreement to abide by the following terms, and subject
  29.         to these terms, Apple grants you a personal, non-exclusive license, under Apple’s
  30.         copyrights in this original Apple software (the "Apple Software"), to use,
  31.         reproduce, modify and redistribute the Apple Software, with or without
  32.         modifications, in source and/or binary forms; provided that if you redistribute
  33.         the Apple Software in its entirety and without modifications, you must retain
  34.         this notice and the following text and disclaimers in all such redistributions of
  35.         the Apple Software.  Neither the name, trademarks, service marks or logos of
  36.         Apple Computer, Inc. may be used to endorse or promote products derived from the
  37.         Apple Software without specific prior written permission from Apple.  Except as
  38.         expressly stated in this notice, no other rights or licenses, express or implied,
  39.         are granted by Apple herein, including but not limited to any patent rights that
  40.         may be infringed by your derivative works or by other works in which the Apple
  41.         Software may be incorporated.
  42.  
  43.         The Apple Software is provided by Apple on an "AS IS" basis.  APPLE MAKES NO
  44.         WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED
  45.         WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  46.         PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN
  47.         COMBINATION WITH YOUR PRODUCTS.
  48.  
  49.         IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR
  50.         CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  51.         GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  52.         ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION
  53.         OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT
  54.         (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN
  55.         ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  56.  
  57.     Change History (most recent first):
  58.         Fri, Jan 28, 2000 -- created
  59. */
  60.  
  61. #define TARGET_API_MAC_CARBON 1
  62.  
  63.  
  64. #ifndef __STUPCONTROL__
  65. #define __STUPCONTROL__
  66.  
  67. #include <Types.h>
  68. #include <Controls.h>
  69.  
  70.  
  71. /* part codes */
  72.  
  73. /* kSTUPTextPart is the part code we return to indicate the user has clicked
  74.     in the text area of our control */
  75. #define kSTUPTextPart 1
  76.  
  77. /* kSTUPScrollPart is the part code we return to indicate the user has clicked
  78.     in the scroll bar part of the control. */
  79. #define kSTUPScrollPart 2
  80.  
  81.  
  82. /* routines for using existing user pane controls.
  83.     These routines are useful for cases where you would like to use an
  84.     existing user pane control in, say, a dialog window as a scrolling
  85.     text edit field.*/
  86.     
  87. /* STUPOpenControl initializes a user pane control so it will be drawn
  88.     and will behave as a scrolling text edit field inside of a window.
  89.     This routine performs all of the initialization steps necessary,
  90.     except it does not create the user pane control itself.  theControl
  91.     should refer to a user pane control that you have either created
  92.     yourself or extracted from a dialog's control heirarchy using
  93.     the GetDialogItemAsControl routine.  */
  94. OSStatus STUPOpenControl(ControlHandle theControl);
  95.  
  96. /* STUPCloseControl deallocates all of the structures allocated
  97.     by STUPOpenControl.  */
  98. OSStatus STUPCloseControl(ControlHandle theControl);
  99.  
  100.  
  101.  
  102. /* routines for creating new scrolling text user pane controls.
  103.     These routines allow you to create new scrolling text
  104.     user pane controls. */
  105.  
  106. /* STUPCreateControl creates a new user pane control and then it passes it
  107.     to STUPOpenControl to initialize it as a scrolling text user pane control. */
  108. OSStatus STUPCreateControl(WindowPtr theWindow, Rect *bounds, ControlHandle *theControl);
  109.  
  110. /* STUPDisposeControl calls STUPCloseControl and then it calls DisposeControl. */
  111. OSStatus STUPDisposeControl(ControlHandle theControl);
  112.  
  113.  
  114. /* Utility Routines */
  115.  
  116. /* STUPSetFont allows you to set the text font, size, and style that will be
  117.     used for displaying text in the edit field.  This implementation uses old
  118.     style text edit records for text,  what ever font you specify will affect
  119.     the appearance of all of the text being displayed inside of the STUPControl. */
  120. OSStatus STUPSetFont(ControlHandle theControl, short theFont, short theSize, Style theStyle);
  121.  
  122. /* STUPSetText sets the text that will be displayed inside of the STUP control.
  123.     The text view and the scroll bar are re-drawn appropriately
  124.     to reflect the new text. */
  125. OSStatus STUPSetText(ControlHandle theControl, char* text, long count);
  126.  
  127. /* STUPGetText returns the current text data being displayed inside of
  128.     the STUPControl.  theText is a handle you create and pass to
  129.     the routine.  */
  130. OSStatus STUPGetText(ControlHandle theControl, Handle theText);
  131.  
  132.  
  133. /* STUPSetSelection sets the text selection and autoscrolls the text view
  134.     so either the cursor or the selction is in the view. */
  135. void STUPSetSelection(ControlHandle theControl, short selStart, short selEnd);
  136.  
  137.  
  138. /* TextFieldSetupResource is a resource format you can use that allows
  139.     to conveniently set the default contents of a STUPControl.  There
  140.     is a ResEdit template for a STUP resource included with this
  141.     project. */
  142.  
  143. enum {
  144.     kSTUPResourceType = 'STUP',
  145.     kTEXTResourceType = 'TEXT'
  146. };
  147. #pragma options align=mac68k
  148. typedef struct {
  149.     short theFont;
  150.     short theSize;
  151.     short theStyle;
  152.     short textresourceID; /* resource id for a 'TEXT' resource.  this text willbe displayed in the STUP Control */
  153. } TextFieldSetupResource;
  154. #pragma options align=reset
  155.  
  156. /* STUPFillControl looks for a 'STUP' resource.  If it finds one, then
  157.     it sets the font and text in the STUP Control using the parameters
  158.     specified in the 'STUP' resource. */
  159. OSStatus STUPFillControl(ControlHandle theControl, short STUPrsrcID);
  160.  
  161.  
  162.  
  163. /* IsSTUPControl returns true if theControl is not NULL
  164.     and theControl refers to a STUP Control.  */
  165. Boolean IsSTUPControl(ControlHandle theControl);
  166.  
  167.  
  168.  
  169. /* Edit commands for STUP Controls. */
  170. enum {
  171.     kSTUPCut = 1,
  172.     kSTUPCopy = 2,
  173.     kSTUPPaste = 3,
  174.     kSTUPClear = 4
  175. };
  176.  
  177.  
  178. /* STUPDoEditCommand performs the editing command specified
  179.     in the editCommand parameter.  The STUPControl's text
  180.     and scroll bar are redrawn and updated as necessary. */
  181. void STUPDoEditCommand(ControlHandle theControl, short editCommand);
  182.  
  183.  
  184. #endif
  185.  
  186.